 /*
  * $Header: /cvshome/build/org.osgi.service.cm/src/org/osgi/service/cm/ConfigurationPlugin.java,v 1.11 2006/06/16 16:31:28 hargrave Exp $
  *
  * Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 package org.osgi.service.cm;

 import java.util.Dictionary ;

 import org.osgi.framework.ServiceReference;

 /**
  * A service interface for processing configuration dictionary before the
  * update.
  *
  * <p>
  * A bundle registers a <code>ConfigurationPlugin</code> object in order to
  * process configuration updates before they reach the Managed Service or
  * Managed Service Factory. The Configuration Admin service will detect
  * registrations of Configuration Plugin services and must call these services
  * every time before it calls the <code>ManagedService</code> or
  * <code>ManagedServiceFactory</code>
  * <code>updated</code> method. The
  * Configuration Plugin service thus has the opportunity to view and modify the
  * properties before they are passed to the ManagedS ervice or Managed Service
  * Factory.
  *
  * <p>
  * Configuration Plugin (plugin) services have full read/write access to all
  * configuration information. Therefore, bundles using this facility should be
  * trusted. Access to this facility should be limited with
  * <code>ServicePermission[ConfigurationPlugin,REGISTER]</code>.
  * Implementations of a Configuration Plugin service should assure that they
  * only act on appropriate configurations.
  *
  * <p>
  * The <code>Integer</code> <code>service.cmRanking</code> registration
  * property may be specified. Not specifying this registration property, or
  * setting it to something other than an <code>Integer</code>, is the same as
  * setting it to the <code>Integer</code> zero. The
  * <code>service.cmRanking</code> property determines the order in which
  * plugins are invoked. Lower ranked plugins are called before higher ranked
  * ones. In the event of more than one plugin having the same value of
  * <code>service.cmRanking</code>, then the Configuration Admin service
  * arbitrarily chooses the order in which they are called.
  *
  * <p>
  * By convention, plugins with <code>service.cmRanking&lt; 0</code> or
  * <code>service.cmRanking &gt; 1000</code> should not make modifications to
  * the properties.
  *
  * <p>
  * The Configuration Admin service has the right to hide properties from
  * plugins, or to ignore some or all the changes that they make. This might be
  * done for security reasons. Any such behavior is entirely implementation
  * defined.
  *
  * <p>
  * A plugin may optionally specify a <code>cm.target</code> registration
  * property whose value is the PID of the Managed Service or Managed Service
  * Factory whose configuration updates the plugin is intended to intercept. The
  * plugin will then only be called with configuration updates that are targetted
  * at the Managed Service or Managed Service Factory with the specified PID.
  * Omitting the <code>cm.target</code> registration property means that the
  * plugin is called for all configuration updates.
  *
  * @version $Revision: 1.11 $
  */
 public interface ConfigurationPlugin {
     /**
      * A service property to limit the Managed Service or Managed Service
      * Factory configuration dictionaries a Configuration Plugin service
      * receives.
      *
      * This property contains a <code>String[]</code> of PIDs. A Configuration
      * Admin service must call a Configuration Plugin service only when this
      * property is not set, or the target service's PID is listed in this
      * property.
      */
     public static final String CM_TARGET = "cm.target";
     /**
      * A service property to specify the order in which plugins are invoked.
      *
      * This property contains an <code>Integer</code> ranking of the plugin.
      * Not specifying this registration property, or setting it to something
      * other than an <code>Integer</code>, is the same as setting it to the
      * <code>Integer</code> zero. This property determines the order in which
      * plugins are invoked. Lower ranked plugins are called before higher ranked
      * ones.
      *
      * @since 1.2
      */
     public static final String CM_RANKING = "service.cmRanking";

     /**
      * View and possibly modify the a set of configuration properties before
      * they are sent to the Managed Service or the Managed Service Factory. The
      * Configuration Plugin services are called in increasing order of their
      * <code>service.cmRanking</code> property. If this property is undefined
      * or is a non- <code>Integer</code> type, 0 is used.
      *
      * <p>
      * This method should not modify the properties unless the
      * <code>service.cmRanking</code> of this plugin is in the range
      * <code>0 &lt;= service.cmRanking &lt;= 1000</code>.
      * <p>
      * If this method throws any <code>Exception</code>, the Configuration
      * Admin service must catch it and should log it.
      *
      * @param reference reference to the Managed Service or Managed Service
      * Factory
      * @param properties The configuration properties. This argument must not
      * contain the "service.bundleLocation" property. The value of this
      * property may be obtained from the
      * <code>Configuration.getBundleLocation</code> method.
      */
     public void modifyConfiguration(ServiceReference reference,
             Dictionary properties);
 }

